home *** CD-ROM | disk | FTP | other *** search
/ Libris Britannia 4 / science library(b).zip / science library(b) / DJGPP / CBGRX103.ZIP / contrib / libgrx / docs / internal.doc < prev    next >
Text File  |  1993-12-06  |  7KB  |  171 lines
  1. Abstract
  2. ========
  3.  
  4. This document describes contains information necessary for rebuilding
  5. the LIBGRX graphics library. Additionally, it describes some internal
  6. details of the library associated with way it accesses the video RAM. This
  7. info might be useful for adding support for new graphics adapter types.
  8.  
  9.  
  10. How to rebuild the library
  11. ==========================
  12.  
  13. The LIBGRX library is built using the Turbo C MAKE. (TC++ 1.01
  14. professional was used.) If an other MAKE has to be used it has to provide
  15. some method for generating response files from long command lines. The
  16. makefiles may have to be changed from the Turbo C MAKE response file
  17. syntax to the syntax of the new MAKE. Additionally, the Turbo C MAKE
  18. provides a C preprocessor-like conditional syntax. If the new MAKE utility
  19. does not support this, the desired option has to be hard-coded.
  20.  
  21. The makefile in the base directory of the package (typically it is
  22. ....djgpp\contrib\libgrx) can be invoked as follows:
  23.  
  24.     1)  make            build DJGPP libraries, and the drivers
  25.     2)  make turboc        build Turbo C libraries
  26.     3)  make test        (1+) build DJGPP test programs
  27.     4)  make turbotst        (2+) build Turbo C test programs
  28.     5)  make install        copy .h and .a files into DJGPP dirs
  29.     6)  make clean        clean up after recompiling
  30.  
  31. All graphics library sources are in the 'src' directory. The makefile
  32. in that directory can also be used to build a customized version of the
  33. library. Customized libraries (and the executable built using them) can be
  34. smaller, because they don't include support for all video RAM access
  35. methods. (see later) The makefile in the src directory can be used as
  36. follows:
  37.  
  38.    make -DPLANES=<value>
  39.        -- or --
  40.    make -DPLANES=<value> [-DMODEL=<memory model>] turboc
  41.  
  42. The value of the PLANES macro determines the included video RAM access
  43. methods. This is a number obtained by OR-ing together the following
  44. values:
  45.  
  46.     1        monochrome (Hercules)
  47.     4        16 color EGA/VGA/SVGA
  48.     8        256 color VGA/SVGA
  49.     16        32768 color SVGA
  50.     32        256 color plane mode (mode X)
  51.  
  52. For example:
  53.  
  54.     make -DPLANES=12
  55.  
  56. will build a DJGPP library which only includes support for 16 and 256
  57. color video modes.
  58.  
  59. To rebuild the Turbo C version of the library a copy of TASM is also
  60. needed, as the library contains a significant amount of in-line assembly
  61. code.
  62.  
  63.  
  64. Compiling the test programs
  65. ===========================
  66.  
  67. The makefile in the test directory accepts the following arguments:
  68.  
  69.     1)  make            build all DJGPP test programs
  70.     2)  make turboc        build all Turbo C test programs
  71.     3)  make <prog>.        build a single DJGPP test program
  72.     4)  make <prog>.exe        build a single Turbo C test program
  73.  
  74. See the accompanying document "tests.doc" on how to run the test programs.
  75.  
  76.  
  77. Low-level video RAM access support
  78. ==================================
  79.  
  80. When 'GrSetMode' is called it finally ends up making a call to the mode
  81. set routine of the graphics driver which knows about the capabilities of
  82. the card, and how to put the card into the desired mode. (This is card
  83. dependent -- that's why there are so many drivers.)
  84.  
  85. Having done this, the driver returns a status word to the library
  86. which specifies the MEMORY ORGANIZATION of the selected graphics mode.
  87. There are MUCH FEWER possible memory organizations than video drivers. The
  88. currently supported memory organizations in LIBGRX are the following:
  89.  
  90.     256 color VGA
  91.     16 color EGA/VGA/SVGA
  92.     32768 color SVGA
  93.     8514/A and S3 hardware accelerated video RAM access
  94.  
  95. The following two memory organizations are not supported yet, but stubs
  96. have been included for them in the library:
  97.  
  98.     monochrome (Hercules, CGA 640x200 mode, EGA, VGA)
  99.     VGA 256 color plane-oriented (Mode X, Y...)
  100.  
  101. The driver status word is used to set up some global variables
  102. describing the layout of the video memory, the number of colors, etc.. The
  103. library contains different low-level video RAM access routines for the
  104. different video RAM organizations. These low-level video RAM access
  105. routines are called indirectly via function pointers. These function
  106. pointers are set up when a graphics primitive first attempts to use them.
  107. This means that an attempt to draw anything before the first call to
  108. 'GrSetMode' will fail miserably as the library will has no idea about the
  109. video access method to be used.
  110.  
  111. The library source files containing the memory mode specific functions
  112. are named as follows:
  113.  
  114.     p1*.c        - monochrome (currently dummies only)
  115.     p4*.c        - EGA/VGA 16 color modes
  116.     p8*.c        - VGA 256 color modes
  117.     ph*.c        - VGA 32768 color mode
  118.     px*.c        - VGA 256 color mode X (currently dummies only)
  119.     pi*.c        - 8514/A and S3 256 color mode
  120.     ps*.c        - a few additional S3 routines where its programming
  121.               differs from the 8514/A
  122.  
  123. Each memory mode access group contains ten files (one function in each)
  124. which do the following:
  125.  
  126.     p?init.c    - global data and possibly an init function
  127.     p?pixset.c    - set a single pixel
  128.     p?pixrd.c    - read a single pixel
  129.     p?pixrow.c    - set a pixel row
  130.     p?pixcol.c    - set a pixel column
  131.     p?pixblk.c    - set a rectangular pixel block
  132.     p?bitblt.c    - copy a rectangular pixel block
  133.     p?line.c    - draw a line
  134.     p?char.c    - draw a character
  135.     p?fillp.c    - fill a pixel row with a pattern
  136.  
  137. The library does all mode-specific video RAM access through these nine
  138. functions. There is a small amount of mode specific code related to
  139. setup and color management in the files "setmode.c", "layout.c",
  140. "context.c" and "colors.c", other than these the rest of the library
  141. (drawing functions, etc..) is video RAM organization independent.
  142.  
  143. If the library was built to support only a single memory organization
  144. then the calls to the appropriate low-level functions are hard-coded into
  145. the code (via preprocessor macros in "libgrx.h"). Additionally, in 256 and
  146. 32768 color modes some trivial pixel manipulations (read and set a single
  147. pixel) are expanded in-line.
  148.  
  149. If the library supports more than one video RAM model then this
  150. in-line expansion is not done, and all low-level access functions are
  151. called via pointers. There is a dispatch routine for every low-level
  152. service (in the files "sw*.c"). The pointers initially point to these
  153. dispatch routines. When a dispatch routine is first called it puts the
  154. address of the appropriate (i.e. corresponding to the current video mode)
  155. low-level access function into the pointer and then calls it. This way the
  156. dispatch routine gets called only the first time a video RAM access
  157. function is used. A call to 'GrSetMode' resets the pointers to point to
  158. the dispatch routines.
  159.  
  160. NOTE: The Turbo C low-level video RAM access routines do not support
  161. paging. (Actually, the 32 bit routines do not support it either because it
  162. is handled transparently by the 386's page fault mechanism and the DOS
  163. extender.) For this reason the Turbo C version has a resolution
  164. limitation: 320x200 in 256 color mode and 800x600 in 16 color mode. For
  165. the same reason there is no support for the 32768 color modes in the
  166. Turbo C version of the library. HOWEVER: the 8514/A and S3 accelerators
  167. do not need direct video RAM access and paging. For this reason the
  168. full resolution of these boards (1024x768x256) can be supported even in the
  169. Turbo C version of the library.
  170.  
  171.